Developer Documentation

QuickTime 4 API Documentation

Inside Macintosh: QuickTime

Previous | Overview | Contents | Next |

Working With Data References

Media structures identify how and where to find their sample data by means of data references. For sound and video media, data references identify files that contain media data; the media data is stored in the data forks of these files. Media handlers use these data references in order to manipulate media data. A single media may contain one or more data references.

Each data reference contains type information that identifies how the reference is specified. Most QuickTime data references use alias information to locate the corresponding files (see Inside Macintosh: Files for more information about aliases and the Alias Manager). The type value for data references that use aliases is 'alis' . Note that the Movie Toolbox uses aliases even on Macintosh computers that do not have System 7 installed--your application can use Alias Manager routines if the Movie Toolbox is installed. See "The Movie Toolbox and System 6" for more information.

The Movie Toolbox identifies a media's data references with an index value. Index values always range from 1 to the number of references in the media. Data reference indexes provide a convenient way to access each reference in a media.

The Movie Toolbox provides a set of functions that allow you to work with data references. This section describes those functions.

You can use the GetMediaDataRef function to retrieve information about a media's data reference. You can add a data reference to a media by calling the AddMediaDataRef function. The SetMediaRef function lets you change which file a specified media associates with its data storage.

Your application can determine the number of data references in a media by calling the GetMediaDataRefCount function.

AddMediaDataRef

The AddMediaDataRef function adds a data reference to a media.

pascal OSErr AddMediaDataRef (Media theMedia, short *index,
                                         Handle dataRef,
                                         OSType dataRefType);
theMedia
Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

index
Contains a pointer to a short integer. The Movie Toolbox returns the index value that is assigned to the new data reference. Your application can use this index to identify the reference to other Movie Toolbox functions, such as GetMediaDataRef (described on GetMediaDataRef ). If the Movie Toolbox cannot add the data reference to the media, it sets the returned index value to 0.

dataRef
Specifies the data reference. This parameter contains a handle to the information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter.

dataRefType
Specifies the type of data reference. If the data reference is an alias, you must set this parameter to rAliasType ('alis') , indicating that the reference is an alias. See Inside Macintosh: Files for more information about aliases and the Alias Manager.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

SetMediaDataRef

The SetMediaDataRef function changes the file that the specified media identifies as the location for its data storage.

pascal OSErr SetMediaDataRef (Media themedia, short index,
                                         Handle dataRef, OSType dataRefType);
themedia
Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

index
Contains a pointer to a short integer. The Movie Toolbox returns the index value that is assigned to the new data reference. Your application can use this index to identify the reference to other Movie Toolbox functions, such as GetMediaDataRef (described on GetMediaDataRef ). As with all data reference functions, the index starts with 1. If the Movie Toolbox cannot add the data reference to the media, it sets the returned index value to 0.

dataRef
Specifies the data reference. This parameter contains a handle to the information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter.

dataRefType
Specifies the type of data reference. If the data reference is an alias, you must set this parameter to rAliasType ('alis') , indicating that the reference is an alias. See Inside Macintosh: Files for more information about aliases and the Alias Manager.

SPECIAL CONSIDERATIONS

Don't call this function unless you have a really good reason. However, if you want to resolve your own missing data references, or you are developing a special-purpose kind of application, SetMediaDataRef may be quite useful.

GetMediaDataRef

The GetMediaDataRef function returns a copy of a specified data reference. Your application identifies the data reference with the appropriate data reference index.

pascal OSErr GetMediaDataRef (Media theMedia, short index,
                                         Handle *dataRef,
                                         OSType *dataRefType,
                                         long *dataRefattributes);
theMedia
Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

index
Identifies the data reference. You provide the index value that corresponds to the data reference. It must be less than or equal to the value that is returned by the GetMediaDataRefCount function, described in the previous section.

dataRef
Contains a pointer to a field that is to receive a handle to the data reference. The media handler returns a handle to information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter. If the function cannot locate the specified data reference, the handler sets this returned value to nil . Set the dataRef parameter to nil if you are not interested in this information.

dataRefType
Contains a pointer to a field that is to receive the type of data reference. If the data reference is an alias, the media handler sets this value to 'alis' , indicating that the reference is an alias. Set the dataRefType parameter to nil if you are not interested in this information.

dataRefattributes
Contains a pointer to a field that is to receive the reference's attribute flags. The following flags are available (unused flags are set to 0):

dataRefSelfReference
Indicates whether the data reference refers to the movie resource's data file. If this flag is set to 1, the data reference identifies media data that is stored in the same file as the movie resource.

dataRefWasNotResolved
Indicates whether the Movie Toolbox resolved the data reference. If this flag is set to 1, the Movie Toolbox could not resolve the data reference. For example, the toolbox may be unable to resolve data references because the required storage device is unavailable at the time a movie is loaded. If the data reference is unresolved, the Movie Toolbox disables the corresponding track.

Set the dataRefAttributes parameter to nil if you are not interested in this information.

DESCRIPTION

You can use GetMediaDataRef function to retrieve information about a data reference. For example, you might want to verify the condition of a movie's data references after loading the movie from its movie file. You could use this function to check each data reference.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

SEE ALSO

You can add a data reference to a media by calling the AddMediaDataRef function, which is described on AddMediaDataRef . You must dispose of a media's data references yourself by disposing of its handle. You can determine the number of data references in a media by calling the GetMediaDataRefCount function, which is described in the previous section.

GetMediaDataRefCount

The GetMediaDataRefCount function allows your application to determine the number of data references in a media.

pascal OSErr GetMediaDataRefCount (Media theMedia, short *count);
theMedia
Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

count
Contains a pointer to a field that is to receive the number of data references in the media.

DESCRIPTION

The count of references in a media corresponds to the maximum index value of any reference in the media. You can use this value to control a loop in which you retrieve all of a media's data references, using the GetMediaDataRef function, which is described in the next section.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

© 1999 Apple Computer, Inc.

Previous | Overview | Contents | Next